Typical HAL CRYP use cases for migration

This section provides typical HAL CRYP use cases to help migrate from HAL1 CRYP to HAL2 CRYP.

Use case: encryption/decryption in polling mode

Sequence diagram

Encryption/decryption in polling mode

@startuml participant "Application" as App participant "CRYP" as CRYP note over App,CRYP: Encryption App -> CRYP: HAL_CRYP_Encrypt() group opt note over App,CRYP: Tag generation App -> CRYP: HAL_CRYPEx_AESGCM_GenerateAuthTAG() note right: **Only for GCM algorithm** App -> CRYP: HAL_CRYPEx_AESCCM_GenerateAuthTAG() note right: **Only for CCM algorithm** end group note over App,CRYP: Decryption App -> CRYP: HAL_CRYP_Decrypt() group opt note over App,CRYP: Tag generation App -> CRYP: HAL_CRYPEx_AESGCM_GenerateAuthTAG() note right: **Only for GCM algorithm** App -> CRYP: HAL_CRYPEx_AESCCM_GenerateAuthTAG() note right: **Only for CCM algorithm** end group @enduml

Code snippet

HAL1

HAL2 

/* Encryption */
HAL_CRYP_Encrypt(&hcryp, Plaintext, PLAINTEXT_SIZE,
                 EncryptedText, TIMEOUT_VALUE);

/* Only for GCM algorithm */
HAL_CRYPEx_AESGCM_GenerateAuthTAG(&hcryp,TAG,
                                        TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_CRYPEx_AESCCM_GenerateAuthTAG(&hcryp,TAG,
                                        TIMEOUT_VALUE);

/* Decryption */
HAL_CRYP_Decrypt(&hcryp,Ciphertext , PLAINTEXT_SIZE,
                 DecryptedText, TIMEOUT_VALUE);

/* Only for GCM algorithm */
HAL_CRYPEx_AESGCM_GenerateAuthTAG(&hcryp,TAG,
                                        TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_CRYPEx_AESCCM_GenerateAuthTAG(&hcryp,TAG,
                                        TIMEOUT_VALUE);

/* Encryption */
HAL_CRYP_Encrypt(&hcryp, Plaintext, PLAINTEXT_SIZE ,
                       EncryptedText, TIMEOUT_VALUE);

/* Only for GCM algorithm */
HAL_CRYP_GCM_GenerateAuthTAG(&hahcryps,TAG,
                                     TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_CRYP_CCM_GenerateAuthTAG(&hcryp,TAG,
                                     TIMEOUT_VALUE);

/* Decryption */
HAL_CRYP_Decrypt(&hcryp, Ciphertext, PLAINTEXT_SIZE ,
                        DecryptedText, TIMEOUT_VALUE);

/* Only for GCM algorithm */
HAL_CRYP_GCM_GenerateAuthTAG(&hcryp,TAG,
                                      TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_CRYP_CCM_GenerateAuthTAG(&hcryp,TAG,
                                     TIMEOUT_VALUE);

Key changes

  1. Tag generation APIs are renamed from HAL_CRYPEx_AES* to HAL_CRYP_* for GCM and CCM algorithms.

  2. Polling-mode encryption and decryption APIs keep the same names (HAL_CRYP_Encrypt() / HAL_CRYP_Decrypt()).

Use case: encryption/decryption in interrupt mode

Sequence diagram

Encryption/decryption in interrupt mode

@startuml participant "Application" as App participant "CRYP" as CRYP note over App,CRYP: Encryption App -> CRYP: HAL_CRYP_Encrypt_IT() group opt note over App,CRYP: Tag generation App -> CRYP: HAL_CRYPEx_AESGCM_GenerateAuthTAG() note right: **Only for GCM algorithm** App -> CRYP: HAL_CRYPEx_AESCCM_GenerateAuthTAG() note right: **Only for CCM algorithm** end group note over App,CRYP: Decryption App -> CRYP: HAL_CRYP_Decrypt_IT() group opt note over App,CRYP: Tag generation App -> CRYP: HAL_CRYPEx_AESGCM_GenerateAuthTAG() note right: **Only for GCM algorithm** App -> CRYP: HAL_CRYPEx_AESCCM_GenerateAuthTAG() note right: **Only for CCM algorithm** end group @enduml

Code snippet

HAL1

HAL2 

/* Encryption */
HAL_CRYP_Encrypt_IT(&hcryp, Plaintext, PLAINTEXT_SIZE,
                         EncryptedText);

/* Only for GCM algorithm */
HAL_CRYPEx_AESGCM_GenerateAuthTAG(&hcryp,TAG,
                                        TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_CRYPEx_AESCCM_GenerateAuthTAG(&hcryp,TAG,
                                        TIMEOUT_VALUE);

/* Decryption */
HAL_CRYP_Decrypt_IT(&hcryp,Ciphertext , PLAINTEXT_SIZE,
                         DecryptedText);

/* Only for GCM algorithm */
HAL_CRYPEx_AESGCM_GenerateAuthTAG(&hcryp,TAG,
                                        TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_CRYPEx_AESCCM_GenerateAuthTAG(&hcryp,TAG,
                                        TIMEOUT_VALUE);

/* Encryption */
HAL_CRYP_Encrypt_IT(&hcryp, Plaintext, PLAINTEXT_SIZE,
                                       EncryptedText);

/* Only for GCM algorithm */
HAL_CRYP_GCM_GenerateAuthTAG(&hcryp,TAG,
                                      TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_CRYP_CCM_GenerateAuthTAG(&hcryp,TAG,
                                     TIMEOUT_VALUE);

/* Decryption */
HAL_CRYP_Decrypt_IT(&hcryp, Ciphertext, PLAINTEXT_SIZE,
                                        DecryptedText);

/* Only for GCM algorithm */
HAL_CRYP_GCM_GenerateAuthTAG(&hcryp,TAG,
                                      TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_CRYP_CCM_GenerateAuthTAG(&hcryp,TAG,
                                     TIMEOUT_VALUE);

Key changes

  1. Interrupt-mode encryption and decryption APIs keep the same names (HAL_CRYP_Encrypt_IT() / HAL_CRYP_Decrypt_IT()).

  2. Tag generation APIs are renamed from HAL_CRYPEx_AES* to HAL_CRYP_* for GCM and CCM algorithms.

Related examples in HAL2

Example name

Brief

example_hal_cryp_cipher_aes_cbc_it

How to use the CRYP peripheral to encrypt/decrypt data (plaintext/ciphertext) in interrupt mode using CRYP CBC.

Use case: encryption/decryption in DMA mode

Sequence diagram

Encryption/decryption in DMA mode

@startuml participant "Application" as App participant "CRYP" as CRYP note over App,CRYP: Encryption App -> CRYP: HAL_CRYP_Encrypt_DMA() group opt note over App,CRYP: Tag generation App -> CRYP: HAL_CRYPEx_AESGCM_GenerateAuthTAG() note right: **Only for GCM algorithm** App -> CRYP: HAL_CRYPEx_AESCCM_GenerateAuthTAG() note right: **Only for CCM algorithm** end group note over App,CRYP: Decryption App -> CRYP: HAL_CRYP_Decrypt_DMA() group opt note over App,CRYP: Tag generation App -> CRYP: HAL_CRYPEx_AESGCM_GenerateAuthTAG() note right: **Only for GCM algorithm** App -> CRYP: HAL_CRYPEx_AESCCM_GenerateAuthTAG() note right: **Only for CCM algorithm** end group @enduml

Code snippet

HAL1

HAL2 

/* Encryption */
HAL_CRYP_Encrypt_DMA(&hcryp, Plaintext, PLAINTEXT_SIZE,
                         EncryptedText);

/* Only for GCM algorithm */
HAL_CRYPEx_AESGCM_GenerateAuthTAG(&hcryp,TAG,
                                        TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_CRYPEx_AESCCM_GenerateAuthTAG(&hcryp,TAG,
                                        TIMEOUT_VALUE);

/* Decryption */
HAL_CRYP_Decrypt_DMA(&hcryp,Ciphertext , PLAINTEXT_SIZE,
                         DecryptedText);

/* Only for GCM algorithm */
HAL_CRYPEx_AESGCM_GenerateAuthTAG(&hcryp,TAG,
                                        TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_CRYPEx_AESCCM_GenerateAuthTAG(&hcryp,TAG,
                                        TIMEOUT_VALUE);

/* Encryption */
HAL_CRYP_Encrypt_DMA(&hcryp, Plaintext, PLAINTEXT_SIZE ,
                                       EncryptedText);

/* Only for GCM algorithm */
HAL_CRYP_GCM_GenerateAuthTAG(&hcryp,TAG,
                                      TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_CRYP_CCM_GenerateAuthTAG(&hcryp,TAG,
                                     TIMEOUT_VALUE);

/* Decryption */
HAL_CRYP_Decrypt_DMA(&hcryp, Ciphertext, PLAINTEXT_SIZE ,
                                        DecryptedText);

/* Only for GCM algorithm */
HAL_CRYP_GCM_GenerateAuthTAG(&hcryp,TAG,
                                      TIMEOUT_VALUE);

/* Only for CCM algorithm */
HAL_CRYP_CCM_GenerateAuthTAG(&hcryp,TAG,
                                     TIMEOUT_VALUE);

Key changes

  1. DMA-mode encryption and decryption APIs keep the same names (HAL_CRYP_Encrypt_DMA() / HAL_CRYP_Decrypt_DMA()).

  2. Tag generation APIs are renamed from HAL_CRYPEx_AES* to HAL_CRYP_* for GCM and CCM algorithms.

Related examples in HAL2

Example name

Brief

example_hal_cryp_cipher_aes_cbc_dma

How to use the CRYP peripheral to encrypt/decrypt data (plaintext/ciphertext) using CRYP CBC algorithm in DMA mode with swapping.

Use case: suspend/resume mode

Sequence diagram

Suspend/resume mode

@startuml participant "Application" as App participant "CRYP" as CRYP note over App,CRYP: CRYP initialization App -> CRYP: HAL_CRYP_Init() note over App,CRYP: Low priority block Encryption App -> CRYP: HAL_CRYP_Encrypt_IT() note over App,CRYP: Low priority process suspending App -> CRYP: HAL_CRYP_ProcessSuspend() App -> CRYP: HAL_CRYP_Suspend() note over App,CRYP: High priority process starting App -> CRYP: HAL_CRYP_Init() note over App,CRYP: Decrypt high priority block App -> CRYP: HAL_CRYP_Decrypt_IT() note over App,CRYP: Resume low priority block processing App -> CRYP: HAL_CRYP_Resume() @enduml

Code snippet

HAL1

HAL2 

/* Set the CRYP parameters */
hcryp.Instance = CRYP;

/* Set the CRYP parameters */
hcryp.Init.DataType = CRYP_BYTE_SWAP;
hcryp.Init.KeySize = CRYP_KEYSIZE_128B;
hcryp.Init.pKey     = AESKey128;
hcryp.Init.Algorithm = CRYP_AES_ECB;
HAL_CRYP_Init(&hcryp);

/* Low prio block Encryption */
HAL_CRYP_Encrypt_IT(&hcryp, Plaintext_8, 128, Encryptedtext);


/* request suspension */
HAL_CRYP_ProcessSuspend(&hcryp);


/* Suspend low prio block processing */
HAL_CRYP_Suspend(&hcryp);

/* -- Thread 1 released the CRYP peripheral and informed Thread 2 ---> */

















/* Resume low prio block processing */
HAL_CRYP_Resume(&hcryp);

/*  */








/* <--- Thread 2 asks to use the CRYP peripheral for a high-priority task -- */








/*  High priority block processing  */
/* Set the CRYP parameters */
hcryp.Init.DataType  = CRYP_BIT_SWAP;
hcryp.Init.KeySize   = CRYP_KEYSIZE_256B;
hcryp.Init.pKey      = AESKey256;
hcryp.Init.pInitVect = AESIV;
hcryp.Init.Algorithm = CRYP_AES_CTR;
HAL_CRYP_Init(&hcryp);

/*  Decrypt */
HAL_CRYP_Decrypt_IT(&hcryp, CiphertextAESCTR256_HighPrio,
                                                16, Decryptedtext_HighPrio);

/* <--- Thread 1 releases the CRYP peripheral so that the low-priority task can resume -- */

/* Set the CRYP parameters */
HAL_CRYP_Init(&hcryp,HAL_CRYP);
HAL_CRYP_AES_ECB_SetConfig(&hcryp);
HAL_CRYP_SetDataSwapping(&hcryp, HAL_CRYP_DATA_SWAPPING_BYTE);
HAL_CRYP_AES_SetNormalKey(&hcryp, HAL_CRYP_KEY_SIZE_128BIT, CRYPKey128);

/* Low prio block Encryption */
HAL_CRYP_Encrypt_IT(&hcryp, Plaintext_8, 128 , Encryptedtext);


/* request suspension */
HAL_CRYP_RequestSuspend(&hcryp);

/* --------------------- Wait for suspend callback -------------------*/

/* Suspend low prio block processing */
HAL_CRYP_SaveContext(&hcryp,&p_context);

/* -- Thread 1 released the CRYP peripheral and informed Thread 2 ---> */

















/* Restore process1 context */
HAL_CRYP_RestoreContext(&hcryp, &p_context);

/* Resume low prio block processing */
HAL_CRYP_Resume(&hcryp);

/*  */








/* <--- Thread 2 asks to use the CRYP peripheral for a high-priority task -- */








/*  High priority block processing  */
/* Set the CRYP parameters */
HAL_CRYP_AES_CTR_SetConfig(&hcryp,AESIV);
HAL_CRYP_SetDataSwapping(&hcryp, HAL_CRYP_DATA_SWAPPING_BIT);
HAL_CRYP_SetNormalKey(&hcryp, HAL_CRYP_KEY_SIZE_256BIT, AESKey256);



/*  Decrypt */
HAL_CRYP_Decrypt_IT(&hcryp, CiphertextAESCTR256_HighPrio,
                                              16, Decryptedtext_HighPrio);

/* --------------------- Wait for decrypt complete callback -------------------*/


/* <--- Thread 1 releases the CRYP peripheral so that the low-priority task can resume -- */

Key changes

  1. HAL2 provides explicit suspend and context management APIs: HAL_CRYP_RequestSuspend(), HAL_CRYP_SaveContext(), and HAL_CRYP_RestoreContext().

  2. HAL2 uses dedicated configuration functions for the algorithm, key and swapping (for example, HAL_CRYP_AES_ECB_SetConfig() and HAL_CRYP_AES_SetNormalKey()).

Related examples in HAL2

No related example is listed in this document for this use case.